All Databases Inside Mac - Basic Toolbox

GetNewDialog

Create a dialog using 'DLOG' resource parameters

#include <Dialogs.h> Dialog Manager

DialogPtr GetNewDialog(dlgRsrcID, dStorage, behind );

short dlgRsrcID ; resource ID of a 'DLOG' resource

Ptr dStorage ; address of a DialogRecord; NIL=allocate one

WindowPtr behind ; window plane; -1=in front, else= window

returns address of a DialogRecord (or NIL if error)

GetNewDialog reads template ('DLOG') from a resource. It then reads the

associated item list resource ('DITL' with or without an associated 'ictb' item

list for color dialogs), creates a dialog window, and returns a DialogPtr for

use in subsequent Dialog Manager functions. This call will first check to see if

a 'dctb' resource exists and return a pointer to a color GrafPort. If the 'DLOG'

doesn't contain an associated color table resource, it returns a pointer to an

old-style GrafPort. This is the most common way to initiate a dialog.

dlgRsrcID is the ID of a 'DLOG' resource. It contains a template containing

information about the dialog, including color where appropriate. The

resource identifies the window size and position, title, type, and so

forth (see NewCWindow). It also contains the ID of a 'DITL'

resource (with or without an associated 'ictb' auxiliary resource)

that is read into memory and set up as the dialog's item list.

dStorage specifies where the DialogRecord should be stored. It is one of:

NIL (0) Storage is allocated as a non-relocatable object on the heap.

This could cause heap fragmentation later. Use DisposDialog

to get rid of this when you are done.

an address (!=0) The DialogRecord will go into the caller- created buffer

starting at dStorage. Later on, use CloseDialog to release the

dialog record and related storage areas. You will be responsible

for freeing up the space of the DialogRecord itself.

behind specifies the dialog window's plane - whether it's in front of or

behind other windows on the screen. It is one of:

-1 In front of all other windows

else A valid WindowPtr; new dialog window will go behind this one

Returns: a DialogPtr (the address of a DialogRecord) that contains the window

and dialog information. A return value of NIL indicates that the

operation was unsuccessful.

Note: The first fields of a DialogRecord are the same as a

WindowRecord and, in fact the DialogPtr is actually a WindowPtr.

Thus, it may be used anywhere a cGrafPtr, GrafPtr , or

WindowPtr is required (SetPort, ShowWindow, etc.). To

access the unique fields of the DialogRecord, cast the returned

DialogPtr to a DialogPeek. See NewDialog for related

information.

Notes: The dialog color table (similar to a Window Manager window color

table) is copied after it is read into memory but before it is passed to

SetWinColor when its ctSize field is equal to anything but -1. A value of

-1 indicates that the default window colors will be used and no copy need be

made. The result in either case is that 'dctb' can be purged without affecting

the dialog.

The dialog is drawn or kept in visible, depending on the information in the

'DLOG' template. If in visible, use ShowWindow later, to make it appear.

Use behind =-1 for most cases. If you really want to, you can put a

modeless dialog behind another window; e.g., if you figure the user is going

to need it in a minute.

After the 'DITL' item list is read into memory, it is copied and the handle of

the copy is stored into the DialogRecord. Thus, the 'DITL' data ( including its

associated color information in the resource 'ictb') can be purged at any

time. Use CouldDialog to make the dialog's 'WDEF', 'DITL', and related

resources un purgeable.

GetNewDialog does not do any internal error checking on your dialog's

resources. If you call GetNewDialog on a dialog resource that doesn't

exist, your program will probably crash. The solution is to just make sure

your program always has the correct resources before running your

program.

Referenced by (77):